from zope.interface import Interface



class IHarvester(Interface):
    """IHarvest is a minimal harvester interface for sources that do not provide
    a queriable interface.
    """
      
    def harvest(self):
        """This method should return an iterable that iterates over a collection of
        objects that provide the meercat.interfaces.IInstance interface.
        """
      
    def getSource(self):
        """Return the name of the source that this harvester is harvesting from"""
        
      
    def setSource(self, name):
        """Set the name of the source that this harvester is harvesting from"""

class IFileHarvester(IHarvester):
    """ An extension of the base harvester for file based harvesters """
    
    def getFileSource(self):
        """ Return the current file source """
    
    def setFileSource(self, source):
        """ Set a new file source """

class IQueriableHarvester(IHarvester):
    """IQueriableHarvester augments the IHarvester interface by modifying the
    harvest method to allow for optional limitations to be added and adds an
    update method that allows for the retrieval of a single object that implements
    the meercat.interfaces.IInstance interface.
    """
    def harvest(self, limit=None, offset=None, from_date=None, until_date=None):
        """This method should return an iterable that iterates over a collection of
        objects that provide the meercat.interfaces.IInstance interface.
        
        Keyword arguments:
        limit -- Place a restriction on the number of results returned (default None)
        offset -- Start the result set at offset into the full result set (default None)
        from_date -- Restrict results to those that have been added/modified since 
          the provided datetime.datetime object. (default None)
        until_date -- Restrict results to those that were added/modified before the
          provided datetime.datetime object. (default None) """
      
    def get(self, identifier):
        """This method should return a single object that provides the 
        meercat.interfaces.IInstance interface. The resulting objects getIdentifier
        method should return the provided identifier. If the source does not have
        the supplied identifier, a LookupError exception should be raised. """
    
    def count(self):
        """ Return the total number of resources that can be harvested """

class IFileSource(Interface):
    """ A file source that handles getting a local copy of a file for 
    harvesting """
    
    def __call__(self):
        """ Get the files and return a list of file handles or a single file 
        handle """


__all__ = ['IHarvester', 'IFileHarvester',
           'IQueriableHarvester', 'IFileSource']